从0到1搭建Codex TypeScript：安全设置 | 代码质量飙升

▌ 技术引导 安全设置是TypeScript项目稳定运行的底线，我见过太多因为没配置好tsconfig.json导致本地能跑线上报错的悲剧。项目初始化时必须开启严格模式，把strict设为true，否则代码质量会像放飞的风筝一样失控。tsconfig.json中要显式配置moduleResolution为node，否则模块解析会把你绕晕。alias配置要是没用ES模块，反而容易引发路径解析错误，所以得用path或者tsconfig-paths。类型声明文件没写对，编译会直接卡死，我记得有一次因为没加@types/express导致整个项目无法启动。安全设置不是写写注释就能搞定的事，得在构建流程中加入类型检查和lint。 代码质量飙升不靠玄学，靠配置和工具。tsconfig.json中要设置target为ESNext，这样编译出来的代码才不会落后时代。module设为ESNext能减少打包体积，尤其是配合rollup或esbuild时。还有个点别忽视，就是alwaysStrict默认是off，一定要手动打开，否则某些语法错误会被忽略。protractor配置文件里要加allowUnmappedImports，不然会对你导入的第三方库报错。代码质量查起来就是用tsc --noEmit，配合eslint和prettier，这两个必须用一个工具链来管理，别分开搞。 工具链配置不能随便复制粘贴，得自己根据项目结构调整。eslint配置文件里要定义overrides，让测试文件和应用文件用不同的规则。prettier要支持ts的扩展语法，比如TSX文件，否则格式化会出问题。CI阶段得确保tsconfig.json和eslint配置文件同步，否则提交的代码可能在测试环境出问题。别忘记配置type-checker，比如使用tslint或者esbuild，用来在构建前做类型检查。还有个坑，tsconfig.json的resolveJsonModule要配合jest的transform配置，不然测试用的JSON文件会被忽略。 项目结构是影响代码质量的关键因素，我见过太多因为目录混乱导致类型链断掉的项目。如果用monorepo，得确保每个子项目的tsconfig.json都正确配置，尤其是rootDir和outDir。别用node_modules的tsconfig.json，直接在项目根目录写一个统一的配置。模块导入要规范，比如用@/utils而不是./utils，这样alias才能生效。还有个问题，就是types设为'none'时，tsconfig.json里的typeRoots要手动指定，否则不会识别全局类型。 所有这些配置不是为了装逼，而是真实帮助过我。有一次我用tsc --build --clean，结果发现配置文件里没写jsx，导致打包时出错。还有次因为没用tsconfig-paths，运行测试的时候总是找不到模块，差点让我抓狂。代码质量飙升的秘诀是配置要精确，工具要能协同工作，别搞单兵作战。别怕配置多，多一个配置项就能少一个错误。 ▌ 技术参考 一 TypeScript项目的安全设置必须从tsconfig.json入手，特别是strict模式。开启strict后，TypeScript会强制检查变量类型、函数参数、对象属性等，避免隐式类型带来的隐患。在2024年之后，越来越多的项目开始依赖strict模式来保证代码的健壮性。在tsconfig.json中，设置"strict": true，还能通过"noImplicitAny": true进一步细化检查。如果项目中使用了全局变量，可以配合"types": ["node", "jest"]，这样TypeScript会自动导入相关类型声明。 二 模块解析配置是安全设置中容易被忽视的部分，特别是对于多人协作或者模块化开发。在tsconfig.json里，设置"moduleResolution": "node"能让TypeScript按照Node.js的模块寻找规则来解析依赖，避免在导入第三方模块时出错。如果使用了路径别名，比如@，必须搭配"baseUrl"和"paths"配置，否则会报找不到模块的错误。例如，"baseUrl": ".", "paths": {"@/": ["src/"]}，能有效减少相对路径的冗余。 三 类型声明文件的处理必须精确，特别是当项目引入第三方库的时候。如果项目中使用了express，必须要在tsconfig.json里添加"types": ["express"]，否则类型检查会跳过这些模块，导致后续代码出错。而如果项目自己定义了类型，应该在typeRoots里指定类型文件的路径，例如"typeRoots": ["./types", "./node_modules/@types"]"。如果使用了自定义类型，可以结合dts-gen或者tsd来生成对应的声明文件。 四 代码质量的提升要依赖于严格的类型检查和代码规范。开启"strict": true后，TypeScript会抛出更多错误，比如未使用的变量、隐式any等。同时，配合eslint和prettier工具，可以实现代码格式化和静态检查的自动化。在eslint配置文件中，设置"parser": "@typescript-eslint/parser"和"parserOptions": {"project": "./tsconfig.json"}能让eslint识别TypeScript语法。Prettier配置则需要支持TSX文件，避免格式化时出错。 五 配置eslint时，要避免使用默认规则，而是根据项目需求自定义。如果项目中使用了React和TypeScript，可以安装@typescript-eslint/eslint-plugin和eslint-plugin-react，然后在配置文件里添加规则，如"react/jsx-uses-vars": "error"。此外，eslint的overrides配置能区分测试文件和应用文件，避免对测试代码进行不必要的检查。例如，test文件可以只检查语法，不检查变量声明，这样能提高构建效率。 六 Prettier的配置要和TypeScript紧密结合，否则格式化可能会失败。在.prettierrc文件中，指定"printWidth": 80，"tabWidth": 2，"semi": false，"singleQuote": true，这些参数能统一代码风格。如果项目中有TSX文件，必须确保Prettier支持，例如使用"parser": "typescript"。还可以在package.json中添加"prettier": {"semi": false}，让Prettier在构建过程中自动格式化代码。 七 在CI阶段，要确保tsconfig.json和eslint配置文件同步，避免线上代码和本地代码风格不一致。可以使用husky和lint-staged工具，对git commit前的代码进行格式化和类型检查。例如，在husky配置中添加"pre-commit": "npm run lint"，确保每次提交前都会触发检查。此外，CI构建时可以使用tsc --noEmit来检查类型，不生成代码，这样能减少构建时间。 八 模块导入要规范，避免使用相对路径导致代码结构混乱。使用alias配置可以大幅提高可读性，比如在tsconfig.json中设置"baseUrl": ".", "paths": {"@/": ["src/"]}。这样在代码中导入模块时，可以写"@/utils/func"而不是"src/utils/func"。为了确保alias生效，需要在构建工具中配置，比如在webpack中使用tsconfig-paths插件，或者在vite中添加resolve.alias。 九 当项目依赖了较多第三方库时，要确保它们的类型声明文件被正确解析。如果某个库没有提供type声明，会导致TypeScript无法识别其API，进而引发错误。可以使用tsd或者dts-gen来生成类型声明文件，或者手动创建.d.ts文件。此外，配置"types": ["jest", "node"]，让TypeScript自动识别这些库的类型，避免手动添加。 十 项目结构会影响代码的可用性和可维护性，特别是大型项目。建议将代码拆分成多个子项目，每个子项目都有自己的tsconfig.json，这样能避免全局配置混乱。同时，使用"rootDir": "./src"和"outDir": "./dist"，将源代码和编译后的代码分开放，防止源码污染。如果使用了monorepo结构，必须确保各个子项目之间的依赖关系清晰，避免模块找不到。 十一 构建流程的优化是代码质量提升的重要环节。使用tsc --build --clean可以快速清理编译残留，避免因旧缓存导致的错误。如果项目需要动态加载模块，可以启用"resolveJsonModule": true，这样TypeScript能正确处理导入JSON文件的情况。另外，设置"esModuleInterop": true能让TypeScript更好地兼容ES模块，减少模块导入错误。 十二 类型检查的效率直接影响构建速度，尤其是大型项目。可以使用--build参数来开启构建模式，这样TypeScript会缓存类型信息加快后续编译。但要注意，某些配置可能会导致缓存失效，比如修改了typeRoots或者types。为了进一步提速，可以结合esbuild或者tsc --noEmitOnly来只检查类型，不生成代码。 十三 测试文件的代码规范要和主项目区分开，避免不必要的检查。在eslint配置文件中，添加overrides规则，例如： ```javascript "overrides": [ { "files": ["/.spec.ts"], "rules": { "no-unused-vars": "off", "prefer-const": "off" } } ] ``` 这样测试文件就只会检查语法错误，不会对测试代码造成干扰。同时，在jest的配置文件中，设置transform为"ts-jest"，让测试文件能被正确解析。 十四 安全性配置要贯穿整个项目生命周期，包括开发和生产环境。在tsconfig.json中，设置"module": "ESNext"可以确保编译后的代码不会落后时代。如果项目需要兼容旧版浏览器或环境，可以设置"target": "ES2015"，但要确保lint和格式化工具也支持这个目标版本。此外，"noImplicitThis": true能防止this类型错误，避免潜在的运行时问题。 十五 代码质量的提升不能只靠配置，还要依赖工具链的配合。使用tsconfig-paths可以让Node.js环境正确解析模块路径，特别是在测试时。如果项目用了TypeScript和Jest，可以配置jest的moduleNameMapper来处理TypeScript模块，例如： ```json "moduleNameMapper": { "^@/(.)$": "/src/$1" } ``` 这样就能让测试文件正确引用项目中的模块，而不需要额外的路径配置。同时，确保所有工具都使用最新的版本，否则可能会因为兼容性问题导致构建失败。